Create Public Work

POST /obras

Create Public Work

cURL

curl --request POST \
  --url https://api.example.com/obras \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "ejercicioFiscalId": 123,
  "claveUnica": "<string>",
  "nombre": "<string>",
  "descripcion": "<string>",
  "dependenciaId": 123,
  "monto": 123,
  "municipioId": 123,
  "tipoProyectoId": 123,
  "estatusObraId": 123,
  "ubicaciones": [
    {
      "municipioId": 123,
      "direccion": "<string>",
      "localidadReferencia": "<string>",
      "referenciaLugar": "<string>",
      "tipoGeometria": "<string>",
      "geometriaJson": {},
      "orden": 123
    }
  ]
}
'

200

{
  "id": 123,
  "numeroObra": 123,
  "claveUnica": "<string>",
  "nombre": "<string>",
  "descripcion": "<string>",
  "monto": 123,
  "ejercicioFiscalId": 123,
  "dependenciaId": 123,
  "municipioId": 123,
  "tipoProyectoId": 123,
  "estatusObraId": 123,
  "ubicaciones": [
    {}
  ]
}

Creates a new public work (obra) with automatic sequential numbering within the fiscal year.

Authentication & Authorization

This endpoint requires admin role. Regular users cannot create obras.

Headers

Authorization · string · required

Bearer token for authentication with admin role

Authorization: Bearer YOUR_JWT_TOKEN

Content-Type · string · required

Must be application/json

Request Body

ejercicioFiscalId · number · required

Fiscal year ID for this obra

claveUnica · string · required

Unique key for the obra (max 50 characters). Must be unique across all obras.

nombre · string · required

Name of the public work (max 255 characters)

descripcion · string

Detailed description of the obra (optional)

dependenciaId · number · required

Department/dependency ID responsible for this obra

monto · number · required

Budget amount (must be positive, max 2 decimal places)

municipioId · number · required

Municipality ID where the obra is located

tipoProyectoId · number

Project type ID (optional)

estatusObraId · number · required

Work status ID (e.g., planned, in progress, completed)

ubicaciones · array

Array of location objects for this obra (optional)

municipioId · number · required

Municipality ID for this specific location

direccion · string · required

Street address

localidadReferencia · string

Locality reference (optional)

referenciaLugar · string

Place reference (optional)

tipoGeometria · string

Geometry type: PUNTO, RUTA, or POLIGONO (optional, defaults to PUNTO)

geometriaJson · object

GeoJSON geometry data (optional)

orden · number

Display order (optional, defaults to 0)

The numeroObra field is automatically generated based on the fiscal year and does not need to be provided.

Response

Returns the created obra object with all related entities populated.

id · number

Unique identifier for the created obra

numeroObra · number

Auto-generated sequential number within the fiscal year

claveUnica · string

Unique key for the obra

nombre · string

Name of the public work

descripcion · string

Detailed description

monto · number

Budget amount

ejercicioFiscalId · number

Fiscal year ID

dependenciaId · number

Department ID

municipioId · number

Municipality ID

tipoProyectoId · number

Project type ID

estatusObraId · number

Work status ID

ubicaciones · array

Array of created location objects

Example Request

curl -X POST "https://api.yucatan.gob.mx/obras" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "ejercicioFiscalId": 1,
    "claveUnica": "OBRA-2024-001",
    "nombre": "Construcción de Escuela Primaria",
    "descripcion": "Construcción de escuela primaria con 6 aulas",
    "dependenciaId": 1,
    "monto": 2500000.00,
    "municipioId": 1,
    "tipoProyectoId": 1,
    "estatusObraId": 1,
    "ubicaciones": [
      {
        "municipioId": 1,
        "direccion": "Calle 60 x 59, Col. Centro",
        "localidadReferencia": "Centro",
        "referenciaLugar": "Cerca del parque principal",
        "tipoGeometria": "PUNTO",
        "geometriaJson": {
          "type": "Point",
          "coordinates": [-89.6247, 20.9674]
        },
        "orden": 0
      }
    ]
  }'

Example Response

{
  "id": 1,
  "numeroObra": 1,
  "claveUnica": "OBRA-2024-001",
  "nombre": "Construcción de Escuela Primaria",
  "descripcion": "Construcción de escuela primaria con 6 aulas",
  "monto": 2500000.00,
  "ejercicioFiscalId": 1,
  "dependenciaId": 1,
  "municipioId": 1,
  "tipoProyectoId": 1,
  "estatusObraId": 1,
  "ubicaciones": [
    {
      "id": 1,
      "municipioId": 1,
      "direccion": "Calle 60 x 59, Col. Centro",
      "localidadReferencia": "Centro",
      "referenciaLugar": "Cerca del parque principal",
      "tipoGeometria": "PUNTO",
      "geometriaJson": {
        "type": "Point",
        "coordinates": [-89.6247, 20.9674]
      },
      "orden": 0
    }
  ]
}

Error Responses

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Returned when the JWT token is missing, invalid, or expired.

403 Forbidden

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Returned when the authenticated user does not have admin role.

400 Bad Request

{
  "statusCode": 400,
  "message": [
    "ejercicioFiscalId must be a number",
    "claveUnica should not be empty",
    "nombre should not be empty",
    "monto must be a positive number"
  ],
  "error": "Bad Request"
}

Returned when request body validation fails.

409 Conflict

{
  "statusCode": 409,
  "message": "La Clave Única 'OBRA-2024-001' ya existe.",
  "error": "Conflict"
}

Returned when the claveUnica already exists in the database.